/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.commons.configuration;
import java.io.File;
import java.io.FileOutputStream;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.io.OutputStreamWriter;
import java.io.Reader;
import java.io.UnsupportedEncodingException;
import java.io.Writer;
import java.net.HttpURLConnection;
import java.net.MalformedURLException;
import java.net.URL;
import java.net.URLConnection;
import java.util.Iterator;
import java.util.LinkedList;
import java.util.List;
import org.apache.commons.configuration.reloading.InvariantReloadingStrategy;
import org.apache.commons.configuration.reloading.ReloadingStrategy;
import org.apache.commons.lang.StringUtils;
import org.apache.commons.logging.LogFactory;
/**
* <p>Partial implementation of the <code>FileConfiguration</code> interface.
* Developers of file based configuration may want to extend this class,
* the two methods left to implement are <code>{@link FileConfiguration#load(Reader)}</code>
* and <code>{@link FileConfiguration#save(Writer)}</code>.</p>
* <p>This base class already implements a couple of ways to specify the location
* of the file this configuration is based on. The following possibilities
* exist:
* <ul><li>URLs: With the method <code>setURL()</code> a full URL to the
* configuration source can be specified. This is the most flexible way. Note
* that the <code>save()</code> methods support only <em>file:</em> URLs.</li>
* <li>Files: The <code>setFile()</code> method allows to specify the
* configuration source as a file. This can be either a relative or an
* absolute file. In the former case the file is resolved based on the current
* directory.</li>
* <li>As file paths in string form: With the <code>setPath()</code> method a
* full path to a configuration file can be provided as a string.</li>
* <li>Separated as base path and file name: This is the native form in which
* the location is stored. The base path is a string defining either a local
* directory or a URL. It can be set using the <code>setBasePath()</code>
* method. The file name, non surprisingly, defines the name of the configuration
* file.</li></ul></p>
* <p>Note that the <code>load()</code> methods do not wipe out the configuration's
* content before the new configuration file is loaded. Thus it is very easy to
* construct a union configuration by simply loading multiple configuration
* files, e.g.</p>
* <p><pre>
* config.load(configFile1);
* config.load(configFile2);
* </pre></p>
* <p>After executing this code fragment, the resulting configuration will
* contain both the properties of configFile1 and configFile2. On the other
* hand, if the current configuration file is to be reloaded, <code>clear()</code>
* should be called first. Otherwise the properties are doubled. This behavior
* is analogous to the behavior of the <code>load(InputStream)</code> method
* in <code>java.util.Properties</code>.</p>
*
* @author Emmanuel Bourg
* @version $Revision: 712401 $, $Date: 2008-11-08 16:29:56 +0100 (Sa, 08 Nov 2008) $
* @since 1.0-rc2
*/
public abstract class AbstractFileConfiguration extends BaseConfiguration implements FileConfiguration
{
/** Constant for the configuration reload event.*/
public static final int EVENT_RELOAD = 20;
/** Stores the file name.*/
protected String fileName;
/** Stores the base path.*/
protected String basePath;
/** The auto save flag.*/
protected boolean autoSave;
/** Holds a reference to the reloading strategy.*/
protected ReloadingStrategy strategy;
/** A lock object for protecting reload operations.*/
private Object reloadLock = new Object();
/** Stores the encoding of the configuration file.*/
private String encoding;
/** Stores the URL from which the configuration file was loaded.*/
private URL sourceURL;
/** A counter that prohibits reloading.*/
private int noReload;
/**
* Default constructor
*
* @since 1.1
*/
public AbstractFileConfiguration()
{
initReloadingStrategy();
setLogger(LogFactory.getLog(getClass()));
addErrorLogListener();
}
/**
* Creates and loads the configuration from the specified file. The passed
* in string must be a valid file name, either absolute or relativ.
*
* @param fileName The name of the file to load.
*
* @throws ConfigurationException Error while loading the file
* @since 1.1
*/
public AbstractFileConfiguration(String fileName) throws ConfigurationException
{
this();
// store the file name
setFileName(fileName);
// load the file
load();
}
/**
* Creates and loads the configuration from the specified file.
*
* @param file The file to load.
* @throws ConfigurationException Error while loading the file
* @since 1.1
*/
public AbstractFileConfiguration(File file) throws ConfigurationException
{
this();
// set the file and update the url, the base path and the file name
setFile(file);
// load the file
if (file.exists())
{
load();
}
}
/**
* Creates and loads the configuration from the specified URL.
*
* @param url The location of the file to load.
* @throws ConfigurationException Error while loading the file
* @since 1.1
*/
public AbstractFileConfiguration(URL url) throws ConfigurationException
{
this();
// set the URL and update the base path and the file name
setURL(url);
// load the file
load();
}
/**
* Load the configuration from the underlying location.
*
* @throws ConfigurationException if loading of the configuration fails
*/
public void load() throws ConfigurationException
{
if (sourceURL != null)
{
load(sourceURL);
}
else
{
load(getFileName());
}
}
/**
* Locate the specified file and load the configuration. This does not
* change the source of the configuration (i.e. the internally maintained file name).
* Use one of the setter methods for this purpose.
*
* @param fileName the name of the file to be loaded
* @throws ConfigurationException if an error occurs
*/
public void load(String fileName) throws ConfigurationException
{
try
{
URL url = ConfigurationUtils.locate(basePath, fileName);
if (url == null)
{
throw new ConfigurationException("Cannot locate configuration source " + fileName);
}
load(url);
}
catch (ConfigurationException e)
{
throw e;
}
catch (Exception e)
{
throw new ConfigurationException("Unable to load the configuration file " + fileName, e);
}
}
/**
* Load the configuration from the specified file. This does not change
* the source of the configuration (i.e. the internally maintained file
* name). Use one of the setter methods for this purpose.
*
* @param file the file to load
* @throws ConfigurationException if an error occurs
*/
public void load(File file) throws ConfigurationException
{
try
{
load(ConfigurationUtils.toURL(file));
}
catch (ConfigurationException e)
{
throw e;
}
catch (Exception e)
{
throw new ConfigurationException("Unable to load the configuration file " + file, e);
}
}
/**
* Load the configuration from the specified URL. This does not change the
* source of the configuration (i.e. the internally maintained file name).
* Use on of the setter methods for this purpose.
*
* @param url the URL of the file to be loaded
* @throws ConfigurationException if an error occurs
*/
public void load(URL url) throws ConfigurationException
{
if (sourceURL == null)
{
if (StringUtils.isEmpty(getBasePath()))
{
// ensure that we have a valid base path
setBasePath(url.toString());
}
sourceURL = url;
}
// throw an exception if the target URL is a directory
File file = ConfigurationUtils.fileFromURL(url);
if (file != null && file.isDirectory())
{
throw new ConfigurationException("Cannot load a configuration from a directory");
}
InputStream in = null;
try
{
in = url.openStream();
load(in);
}
catch (ConfigurationException e)
{
throw e;
}
catch (Exception e)
{
throw new ConfigurationException("Unable to load the configuration from the URL " + url, e);
}
finally
{
// close the input stream
try
{
if (in != null)
{
in.close();
}
}
catch (IOException e)
{
getLogger().warn("Could not close input stream", e);
}
}
}
/**
* Load the configuration from the specified stream, using the encoding
* returned by {@link #getEncoding()}.
*
* @param in the input stream
*
* @throws ConfigurationException if an error occurs during the load operation
*/
public void load(InputStream in) throws ConfigurationException
{
load(in, getEncoding());
}
/**
* Load the configuration from the specified stream, using the specified
* encoding. If the encoding is null the default encoding is used.
*
* @param in the input stream
* @param encoding the encoding used. <code>null</code> to use the default encoding
*
* @throws ConfigurationException if an error occurs during the load operation
*/
public void load(InputStream in, String encoding) throws ConfigurationException
{
Reader reader = null;
if (encoding != null)
{
try
{
reader = new InputStreamReader(in, encoding);
}
catch (UnsupportedEncodingException e)
{
throw new ConfigurationException(
"The requested encoding is not supported, try the default encoding.", e);
}
}
if (reader == null)
{
reader = new InputStreamReader(in);
}
load(reader);
}
/**
* Save the configuration. Before this method can be called a valid file
* name must have been set.
*
* @throws ConfigurationException if an error occurs or no file name has
* been set yet
*/
public void save() throws ConfigurationException
{
if (getFileName() == null)
{
throw new ConfigurationException("No file name has been set!");
}
if (sourceURL != null)
{
save(sourceURL);
}
else
{
save(fileName);
}
strategy.init();
}
/**
* Save the configuration to the specified file. This doesn't change the
* source of the configuration, use setFileName() if you need it.
*
* @param fileName the file name
*
* @throws ConfigurationException if an error occurs during the save operation
*/
public void save(String fileName) throws ConfigurationException
{
try
{
File file = ConfigurationUtils.getFile(basePath, fileName);
if (file == null)
{
throw new ConfigurationException("Invalid file name for save: " + fileName);
}
save(file);
}
catch (ConfigurationException e)
{
throw e;
}
catch (Exception e)
{
throw new ConfigurationException("Unable to save the configuration to the file " + fileName, e);
}
}
/**
* Save the configuration to the specified URL.
* This doesn't change the source of the configuration, use setURL()
* if you need it.
*
* @param url the URL
*
* @throws ConfigurationException if an error occurs during the save operation
*/
public void save(URL url) throws ConfigurationException
{
// file URLs have to be converted to Files since FileURLConnection is
// read only (http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4191800)
File file = ConfigurationUtils.fileFromURL(url);
if (file != null)
{
save(file);
}
else
{
// for non file URLs save through an URLConnection
OutputStream out = null;
try
{
URLConnection connection = url.openConnection();
connection.setDoOutput(true);
// use the PUT method for http URLs
if (connection instanceof HttpURLConnection)
{
HttpURLConnection conn = (HttpURLConnection) connection;
conn.setRequestMethod("PUT");
}
out = connection.getOutputStream();
save(out);
// check the response code for http URLs and throw an exception if an error occured
if (connection instanceof HttpURLConnection)
{
HttpURLConnection conn = (HttpURLConnection) connection;
if (conn.getResponseCode() >= HttpURLConnection.HTTP_BAD_REQUEST)
{
throw new IOException("HTTP Error " + conn.getResponseCode() + " " + conn.getResponseMessage());
}
}
}
catch (IOException e)
{
throw new ConfigurationException("Could not save to URL " + url, e);
}
finally
{
closeSilent(out);
}
}
}
/**
* Save the configuration to the specified file. The file is created
* automatically if it doesn't exist. This doesn't change the source
* of the configuration, use {@link #setFile} if you need it.
*
* @param file the target file
*
* @throws ConfigurationException if an error occurs during the save operation
*/
public void save(File file) throws ConfigurationException
{
OutputStream out = null;
try
{
// create the file if necessary
createPath(file);
out = new FileOutputStream(file);
save(out);
}
catch (IOException e)
{
throw new ConfigurationException("Unable to save the configuration to the file " + file, e);
}
finally
{
closeSilent(out);
}
}
/**
* Save the configuration to the specified stream, using the encoding
* returned by {@link #getEncoding()}.
*
* @param out the output stream
*
* @throws ConfigurationException if an error occurs during the save operation
*/
public void save(OutputStream out) throws ConfigurationException
{
save(out, getEncoding());
}
/**
* Save the configuration to the specified stream, using the specified
* encoding. If the encoding is null the default encoding is used.
*
* @param out the output stream
* @param encoding the encoding to use
* @throws ConfigurationException if an error occurs during the save operation
*/
public void save(OutputStream out, String encoding) throws ConfigurationException
{
Writer writer = null;
if (encoding != null)
{
try
{
writer = new OutputStreamWriter(out, encoding);
}
catch (UnsupportedEncodingException e)
{
throw new ConfigurationException(
"The requested encoding is not supported, try the default encoding.", e);
}
}
if (writer == null)
{
writer = new OutputStreamWriter(out);
}
save(writer);
}
/**
* Return the name of the file.
*
* @return the file name
*/
public String getFileName()
{
return fileName;
}
/**
* Set the name of the file. The passed in file name can contain a
* relative path.
* It must be used when referring files with relative paths from classpath.
* Use <code>{@link AbstractFileConfiguration#setPath(String)
* setPath()}</code> to set a full qualified file name.
*
* @param fileName the name of the file
*/
public void setFileName(String fileName)
{
sourceURL = null;
this.fileName = fileName;
}
/**
* Return the base path.
*
* @return the base path
* @see FileConfiguration#getBasePath()
*/
public String getBasePath()
{
return basePath;
}
/**
* Sets the base path. The base path is typically either a path to a
* directory or a URL. Together with the value passed to the
* <code>setFileName()</code> method it defines the location of the
* configuration file to be loaded. The strategies for locating the file are
* quite tolerant. For instance if the file name is already an absolute path
* or a fully defined URL, the base path will be ignored. The base path can
* also be a URL, in which case the file name is interpreted in this URL's
* context. Because the base path is used by some of the derived classes for
* resolving relative file names it should contain a meaningful value. If
* other methods are used for determining the location of the configuration
* file (e.g. <code>setFile()</code> or <code>setURL()</code>), the
* base path is automatically set.
*
* @param basePath the base path.
*/
public void setBasePath(String basePath)
{
sourceURL = null;
this.basePath = basePath;
}
/**
* Return the file where the configuration is stored. If the base path is a
* URL with a protocol different than "file", or the configuration
* file is within a compressed archive, the return value
* will not point to a valid file object.
*
* @return the file where the configuration is stored; this can be <b>null</b>
*/
public File getFile()
{
if (getFileName() == null && sourceURL == null)
{
return null;
}
else if (sourceURL != null)
{
return ConfigurationUtils.fileFromURL(sourceURL);
}
else
{
return ConfigurationUtils.getFile(getBasePath(), getFileName());
}
}
/**
* Set the file where the configuration is stored. The passed in file is
* made absolute if it is not yet. Then the file's path component becomes
* the base path and its name component becomes the file name.
*
* @param file the file where the configuration is stored
*/
public void setFile(File file)
{
sourceURL = null;
setFileName(file.getName());
setBasePath((file.getParentFile() != null) ? file.getParentFile()
.getAbsolutePath() : null);
}
/**
* Returns the full path to the file this configuration is based on. The
* return value is a valid File path only if this configuration is based on
* a file on the local disk.
* If the configuration was loaded from a packed archive the returned value
* is the string form of the URL from which the configuration was loaded.
*
* @return the full path to the configuration file
*/
public String getPath()
{
String path = null;
File file = getFile();
// if resource was loaded from jar file may be null
if (file != null)
{
path = file.getAbsolutePath();
}
// try to see if file was loaded from a jar
if (path == null)
{
if (sourceURL != null)
{
path = sourceURL.getPath();
}
else
{
try
{
path = ConfigurationUtils.getURL(getBasePath(), getFileName()).getPath();
}
catch (MalformedURLException e)
{
// simply ignore it and return null
;
}
}
}
return path;
}
/**
* Sets the location of this configuration as a full or relative path name.
* The passed in path should represent a valid file name on the file system.
* It must not be used to specify relative paths for files that exist
* in classpath, either plain file system or compressed archive,
* because this method expands any relative path to an absolute one which
* may end in an invalid absolute path for classpath references.
*
* @param path the full path name of the configuration file
*/
public void setPath(String path)
{
setFile(new File(path));
}
/**
* Return the URL where the configuration is stored.
*
* @return the configuration's location as URL
*/
public URL getURL()
{
return (sourceURL != null) ? sourceURL
: ConfigurationUtils.locate(getBasePath(), getFileName());
}
/**
* Set the location of this configuration as a URL. For loading this can be
* an arbitrary URL with a supported protocol. If the configuration is to
* be saved, too, a URL with the "file" protocol should be
* provided.
*
* @param url the location of this configuration as URL
*/
public void setURL(URL url)
{
setBasePath(ConfigurationUtils.getBasePath(url));
setFileName(ConfigurationUtils.getFileName(url));
sourceURL = url;
}
public void setAutoSave(boolean autoSave)
{
this.autoSave = autoSave;
}
public boolean isAutoSave()
{
return autoSave;
}
/**
* Save the configuration if the automatic persistence is enabled
* and if a file is specified.
*/
protected void possiblySave()
{
if (autoSave && fileName != null)
{
try
{
save();
}
catch (ConfigurationException e)
{
throw new ConfigurationRuntimeException("Failed to auto-save", e);
}
}
}
/**
* Adds a new property to this configuration. This implementation checks if
* the auto save mode is enabled and saves the configuration if necessary.
*
* @param key the key of the new property
* @param value the value
*/
public void addProperty(String key, Object value)
{
super.addProperty(key, value);
possiblySave();
}
/**
* Sets a new value for the specified property. This implementation checks
* if the auto save mode is enabled and saves the configuration if
* necessary.
*
* @param key the key of the affected property
* @param value the value
*/
public void setProperty(String key, Object value)
{
super.setProperty(key, value);
possiblySave();
}
public void clearProperty(String key)
{
super.clearProperty(key);
possiblySave();
}
public ReloadingStrategy getReloadingStrategy()
{
return strategy;
}
public void setReloadingStrategy(ReloadingStrategy strategy)
{
this.strategy = strategy;
strategy.setConfiguration(this);
strategy.init();
}
/**
* Performs a reload operation if necessary. This method is called on each
* access of this configuration. It asks the associated reloading strategy
* whether a reload should be performed. If this is the case, the
* configuration is cleared and loaded again from its source. If this
* operation causes an exception, the registered error listeners will be
* notified. The error event passed to the listeners is of type
* <code>EVENT_RELOAD</code> and contains the exception that caused the
* event.
*/
public void reload()
{
synchronized (reloadLock)
{
if (noReload == 0)
{
try
{
enterNoReload(); // avoid reentrant calls
if (strategy.reloadingRequired())
{
if (getLogger().isInfoEnabled())
{
getLogger().info("Reloading configuration. URL is " + getURL());
}
fireEvent(EVENT_RELOAD, null, getURL(), true);
setDetailEvents(false);
boolean autoSaveBak = this.isAutoSave(); // save the current state
this.setAutoSave(false); // deactivate autoSave to prevent information loss
try
{
clear();
load();
}
finally
{
this.setAutoSave(autoSaveBak); // set autoSave to previous value
setDetailEvents(true);
}
fireEvent(EVENT_RELOAD, null, getURL(), false);
// notify the strategy
strategy.reloadingPerformed();
}
}
catch (Exception e)
{
fireError(EVENT_RELOAD, null, null, e);
// todo rollback the changes if the file can't be reloaded
}
finally
{
exitNoReload();
}
}
}
}
/**
* Enters the "No reloading mode". As long as this mode is active
* no reloading will be performed. This is necessary for some
* implementations of <code>save()</code> in derived classes, which may
* cause a reload while accessing the properties to save. This may cause the
* whole configuration to be erased. To avoid this, this method can be
* called first. After a call to this method there always must be a
* corresponding call of <code>{@link #exitNoReload()}</code> later! (If
* necessary, <code>finally</code> blocks must be used to ensure this.
*/
protected void enterNoReload()
{
synchronized (reloadLock)
{
noReload++;
}
}
/**
* Leaves the "No reloading mode".
*
* @see #enterNoReload()
*/
protected void exitNoReload()
{
synchronized (reloadLock)
{
if (noReload > 0) // paranoia check
{
noReload--;
}
}
}
/**
* Sends an event to all registered listeners. This implementation ensures
* that no reloads are performed while the listeners are invoked. So
* infinite loops can be avoided that can be caused by event listeners
* accessing the configuration's properties when they are invoked.
*
* @param type the event type
* @param propName the name of the property
* @param propValue the value of the property
* @param before the before update flag
*/
protected void fireEvent(int type, String propName, Object propValue, boolean before)
{
enterNoReload();
try
{
super.fireEvent(type, propName, propValue, before);
}
finally
{
exitNoReload();
}
}
public Object getProperty(String key)
{
synchronized (reloadLock)
{
reload();
return super.getProperty(key);
}
}
public boolean isEmpty()
{
reload();
return super.isEmpty();
}
public boolean containsKey(String key)
{
reload();
return super.containsKey(key);
}
/**
* Returns an <code>Iterator</code> with the keys contained in this
* configuration. This implementation performs a reload if necessary before
* obtaining the keys. The <code>Iterator</code> returned by this method
* points to a snapshot taken when this method was called. Later changes at
* the set of keys (including those caused by a reload) won't be visible.
* This is because a reload can happen at any time during iteration, and it
* is impossible to determine how this reload affects the current iteration.
* When using the iterator a client has to be aware that changes of the
* configuration are possible at any time. For instance, if after a reload
* operation some keys are no longer present, the iterator will still return
* those keys because they were found when it was created.
*
* @return an <code>Iterator</code> with the keys of this configuration
*/
public Iterator getKeys()
{
reload();
List keyList = new LinkedList();
enterNoReload();
try
{
for (Iterator it = super.getKeys(); it.hasNext();)
{
keyList.add(it.next());
}
return keyList.iterator();
}
finally
{
exitNoReload();
}
}
/**
* Create the path to the specified file.
*
* @param file the target file
*/
private void createPath(File file)
{
if (file != null)
{
// create the path to the file if the file doesn't exist
if (!file.exists())
{
File parent = file.getParentFile();
if (parent != null && !parent.exists())
{
parent.mkdirs();
}
}
}
}
public String getEncoding()
{
return encoding;
}
public void setEncoding(String encoding)
{
this.encoding = encoding;
}
/**
* Creates a copy of this configuration. The new configuration object will
* contain the same properties as the original, but it will lose any
* connection to a source file (if one exists); this includes setting the
* source URL, base path, and file name to <b>null</b>. This is done to
* avoid race conditions if both the original and the copy are modified and
* then saved.
*
* @return the copy
* @since 1.3
*/
public Object clone()
{
AbstractFileConfiguration copy = (AbstractFileConfiguration) super.clone();
copy.setBasePath(null);
copy.setFileName(null);
copy.initReloadingStrategy();
return copy;
}
/**
* Helper method for initializing the reloading strategy.
*/
private void initReloadingStrategy()
{
setReloadingStrategy(new InvariantReloadingStrategy());
}
/**
* A helper method for closing an output stream. Occurring exceptions will
* be ignored.
*
* @param out the output stream to be closed (may be <b>null</b>)
* @since 1.5
*/
private void closeSilent(OutputStream out)
{
try
{
if (out != null)
{
out.close();
}
}
catch (IOException e)
{
getLogger().warn("Could not close output stream", e);
}
}
}